home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / dviware / umddvi / lib / readme < prev    next >
Text File  |  1990-10-01  |  8KB  |  249 lines
  1. This directory is for library routines.  They are hopefully now 99%
  2. portable, but only time (and new machines) will tell.
  3.  
  4. File        Functions
  5. ----------------------------------------------------------------------
  6. bcopy.s        bcopy(from, to, count)
  7.         char *from, *to;
  8.         int count;
  9.  
  10.         Copies `count' bytes from location `from' to
  11.         location `to'
  12. ----------------------------------------------------------------------
  13. bzero.s        bzero(addr, count)
  14.         char *addr;
  15.         int count;
  16.  
  17.         Zeroes `count' bytes starting at location `addr'
  18. ----------------------------------------------------------------------
  19. error.c        error(quit, errno, fmt, arg1, arg2, ...)
  20.         int quit, errno;
  21.         char *fmt;
  22.  
  23.         Prints the message in `fmt' to stderr as would
  24.         fprintf, along with the (optional) system error
  25.         associated with `errno'.  If `quit' is nonzero,
  26.         does an exit(quit).  Give 0 for errno to suppress
  27.         the system error part.
  28. ----------------------------------------------------------------------
  29. findpost.c    FindPostAmble(f)
  30.         FILE *f;
  31.  
  32.         Repositions the file `f' (using fseek(3S)) to
  33.         the beginning of the postamble, such that the next
  34.         getc from f should return DVI_POST.
  35.  
  36.         Returns 0 if successful, -1 otherwise.
  37. ----------------------------------------------------------------------
  38. fio.c        GetLong(f)
  39. [See also    FILE *f;
  40. ../h/fio.h]
  41.         Gets a `long' from file `f' in the format written
  42.         by PutLong.  [This should actually be an `i32'
  43.         function but I am too lazy to go fix that now.]
  44.         ------------------------------------------------------
  45.         Get3Byte(f)
  46.         FILE *f;
  47.  
  48.         Gets a 3 byte integer from file `f' in the format
  49.         written by Put3Byte.  The value is sign extended.
  50.         ------------------------------------------------------
  51.         GetWord(f)
  52.         FILE *f;
  53.  
  54.         Gets a 2 byte integer from file `f'.  The value is
  55.         sign extended.
  56.         ------------------------------------------------------
  57.         GetByte(f)
  58.         FILE *f;
  59.  
  60.         Gets a 1 byte integer from file `f'.  The value is
  61.         sign extended.
  62.  
  63.         All of these have counterparts in ../h/fio.h which
  64.         may be used in speed-critical routines.  However, these
  65.         differ from the fGet* versions in that:
  66.            + these check for EOF (and call error if found);
  67.            + these sign extend their return values.
  68. ----------------------------------------------------------------------
  69. getopt.c    extern char *optarg;
  70. [From Henry    extern int optind;
  71. Spencer @
  72. U of Toronto    int
  73. Zoology]    getopt(argc, argv, optstring)
  74.         int argc;
  75.         char **argv;
  76.         char *optstring;
  77.  
  78.         `argv' and `argc' should be those given to main().
  79.         getopt scans command line arguments according to the
  80.         string in `optstring'.  Arguments are considered to
  81.         start with `-'.  A quick example:
  82.  
  83.             switch (getopt(argc, argv, "bco:s:")) {
  84.             case 'b': ...
  85.  
  86.         would allow the options `-b', `-c', `-o argument', and
  87.         and `-s argument', and would return 'b', 'c', 'o', or
  88.         's', if one of those were specified.  If getopt runs out
  89.         of arguments, it returns EOF; if it encounters an invalid
  90.         option letter (e.g., `-z' in this example) it returns '?'.
  91.  
  92.         If the option has an argument, getopt leaves `optarg'
  93.         pointing to it.
  94.  
  95.         After getopt returns EOF, the remaining arguments (if
  96.         any) are in argv[optind] through argv[argc - 1].
  97. ----------------------------------------------------------------------
  98. ***deprecated***
  99. machint.s    machint(addr, count)
  100.         int *addr;
  101.         int count;
  102.  
  103.         Converts `count' 4 byte integers at location `addr'
  104.         to machine order.  This is used to convert arrays of
  105.         integers in the order generated and written by PutLong
  106.         and GetLong to and from machine order.
  107. ----------------------------------------------------------------------
  108. ***deprecated***
  109. machintnop.c    machint(addr, count)
  110.         int *addr;
  111.         int count;
  112.  
  113.         No-op version for Suns & Pyramids.
  114. ----------------------------------------------------------------------
  115. ***deprecated***
  116. pxl.c        double DMagFactor(magfactor)
  117.         int magfactor;
  118.  
  119.         Returns magfactor/1000.0, with some extra fiddling
  120.         to get more precise values for the various \magstep's
  121.         that are commonly used.
  122.         ------------------------------------------------------
  123.         char *GenPXLFileName(nm, mag, designsize, globalmag, path)
  124.         char *nm;
  125.         int mag, designsize, globalmag;
  126.         char *path;
  127.  
  128.         Returns (in static storage) the name of the PXL
  129.         file given the name of the font `nm', the DVI
  130.         magnification (`at size') `mag', the design
  131.         size `designsize', an additional magnification
  132.         of `globalmag/1000.0', and the assumed path
  133.         `path'.  If path is zero (or *path is 0), the
  134.         constant PXLPATH (from ../h/pxl.h) is used instead.
  135.         `Path' should normally be the value of the
  136.         environment variable ``TEXFONTS''.
  137.         ------------------------------------------------------
  138.         struct pxltail *ReadPXLFile(nm, getrast)
  139.         char *nm;
  140.         int getrast;
  141.  
  142.         Reads the named PXL file and returns a pointer to
  143.         a built-up struct pxltail.  `Nm' should be the
  144.         name as returned by GenPXLFileName.  If `getrast'
  145.         is nonzero, the character rasters will also be
  146.         read in, and the raster pointers in the chinfo
  147.         structures will be set to point to each character's
  148.         raster (or to 0 if the raster is completely blank).
  149. ----------------------------------------------------------------------
  150. ***XXX***
  151. rotate.c    PerformRotation(ch, deg)
  152.         struct chinfo *ch;
  153.         int deg;
  154.  
  155.         Rotates the bitmap of the character `ch', and
  156.         exchanges the height and width fields so that the
  157.         new bitmap is indistinguishable from the original
  158.         as far as those values are concerned.  `deg' is
  159.         the number of degrees of rotation desired and must
  160.         be a multiple of 90.  Currently only -90 (and 270)
  161.         degree rotations are supported (this is one quarter
  162.         turn clockwise).
  163.  
  164.         The rotation is done in place.
  165.  
  166.         In general, this should only be used in the final
  167.         output stages of a device that needs `landscape
  168.         mode' output.
  169. ----------------------------------------------------------------------
  170. ***XXX***
  171. scaletfm.c    ScaleTFMWidths(px, z)
  172.         struct pxltail *px;
  173.         i32 z;
  174.  
  175.         Scales all the TFM widths in px->px_info according to
  176.         the scale factor `z', which should be the `at size'
  177.         from a DVI file (i.e., a number in scaled points).
  178.  
  179.         i32 ScaleOneWidth(width, z)
  180.         i32 width, z;
  181.  
  182.         Scales the (single) TFM width `width' by `z'.
  183. ----------------------------------------------------------------------
  184. scanpost.c    ScanPostAmble(f, headerfunc, fontfunc)
  185.         FILE *f;
  186.         int (*headerfunc)(), (*fontfunc)();
  187.  
  188.         Scans the postamble of a DVI file.  The given functions
  189.         are called with the information gleaned from reading the
  190.         postamble.  Headerfunc is called once, and fontfunc once
  191.         per font definition.
  192.         
  193.         See ../h/postamble.h for the definitions of the
  194.         parameters passed to the two functions.
  195. ----------------------------------------------------------------------
  196. search.c    struct search *SCreate(dsize)
  197.         unsigned dsize;
  198.  
  199.         Creates a search table; keys are i32 integers, data
  200.         objects are of size dsize and of unspecified type.  A
  201.         null pointer is returned if the table cannot be created.
  202.  
  203.         SEnumerate(table, func)
  204.         struct search *table;
  205.         int (*func)();
  206.  
  207.         Invokes the given function on each object in the table.
  208.         The function is handed a "char *" pointer to the objects
  209.         as its first argument and the i32 key as its second.
  210.         (The return value from (*func)(), if any, is ignored;
  211.         technically it should be void (*func)(), but that is
  212.         not implemented quite right in many Unix compilers...)
  213.  
  214.         char *SSearch(table, key, disp)
  215.         struct search *table;
  216.         i32 key;
  217.         int *disp;
  218.  
  219.         Searches for a given key within the given search
  220.         table.  A number of dispositions can be specified;
  221.         see ../h/search.h for the flags that can be specified
  222.         in *disp.  *disp is modified before return to set
  223.         the reason for the search success or failure.  The
  224.         return value is a pointer to the user data area
  225.         for the given key if found, otherwise NULL.
  226.  
  227.         WARNING: data areas may move on future searches that
  228.         create new data objects.
  229. ----------------------------------------------------------------------
  230. seek.c        int Seekable(fd)
  231.         int fd;
  232.  
  233.         Returns true iff the Unix file fd is randomly
  234.         accessible.  (In particular, pipes are not.)
  235.  
  236.         int MakeSeekable(f)
  237.         FILE *f;
  238.  
  239.         If the stdio file f is not seekable, MakeSeekable
  240.         forces it to be so, by copying it to a temporary
  241.         file.  MakeSeekable returns zero on success; -1
  242.         indicates failure.
  243. ----------------------------------------------------------------------
  244. strsave.c    char *strsave(s)
  245.         char *s;
  246.  
  247.         Saves a malloc()ed copy of the C string s.  (Beware:
  248.         exits if out of memory.)
  249.